home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kopete / kopeteplugin.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-09-10  |  6.4 KB  |  218 lines
  1. /*
  2.     kopeteplugin.h - Kopete Plugin API
  3.  
  4.     Copyright (c) 2001-2002 by Duncan Mac-Vicar Prett <duncan@kde.org>
  5.     Copyright (c) 2002-2003 by Martijn Klingens       <klingens@kde.org>
  6.     Copyright (c) 2002-2004 by Olivier Goffart        <ogoffart@ tiscalinet.be>
  7.  
  8.     Copyright (c) 2002-2003 by the Kopete developers  <kopete-devel@kde.org>
  9.  
  10.     *************************************************************************
  11.     *                                                                       *
  12.     * This library is free software; you can redistribute it and/or         *
  13.     * modify it under the terms of the GNU Lesser General Public            *
  14.     * License as published by the Free Software Foundation; either          *
  15.     * version 2 of the License, or (at your option) any later version.      *
  16.     *                                                                       *
  17.     *************************************************************************
  18. */
  19.  
  20. #ifndef KOPETEPLUGIN_H
  21. #define KOPETEPLUGIN_H
  22.  
  23. #include <kxmlguiclient.h>
  24. #include <qobject.h>
  25. #include <kdemacros.h>
  26.  
  27. #include "kopete_export.h"
  28.  
  29. #include <kopetemessage.h> //TODO: remove
  30. namespace DOM  { class Node; }  //TODO: remove
  31. class KAction; //TODO: remove
  32.  
  33.  
  34. class KPluginInfo;
  35.  
  36.  
  37. namespace Kopete
  38. {
  39.  
  40. class MetaContact;
  41.  
  42. /**
  43.  * @brief Base class for all plugins or protocols.
  44.  *
  45.  * To create a plugin, you need to create a .desktop file which looks like that:
  46.  * \verbatim
  47. [Desktop Entry]
  48. Encoding=UTF-8
  49. Type=Service
  50. X-Kopete-Version=1000900
  51. Icon=icon
  52. ServiceTypes=Kopete/Plugin
  53. X-KDE-Library=kopete_myplugin
  54. X-KDE-PluginInfo-Author=Your Name
  55. X-KDE-PluginInfo-Email=your@mail.com
  56. X-KDE-PluginInfo-Name=kopete_myplugin
  57. X-KDE-PluginInfo-Version=0.0.1
  58. X-KDE-PluginInfo-Website=http://yoursite.com
  59. X-KDE-PluginInfo-Category=Plugins
  60. X-KDE-PluginInfo-Depends=
  61. X-KDE-PluginInfo-License=GPL
  62. X-KDE-PluginInfo-EnabledByDefault=false
  63. Name=MyPlugin
  64. Comment=Plugin that do some nice stuff
  65.  \endverbatim
  66.  *
  67.  * The constructor of your plugin should looks like this:
  68.  *
  69.  * \code
  70.     typedef KGenericFactory<MyPlugin> MyPluginFactory;
  71.     static const KAboutData aboutdata("kopete_myplugin", I18N_NOOP("MyPlugin") , "1.0" );
  72.     K_EXPORT_COMPONENT_FACTORY( kopete_myplugin, MyPluginFactory( &aboutdata )  )
  73.  
  74.     MyPlugin::MyPlugin( QObject *parent, const char *name, const QStringList &  args  )
  75.         : Kopete::Plugin( MyPluginFactory::instance(), parent, name )
  76.     {
  77.         //...
  78.     }
  79.  \endcode
  80.  *
  81.  * Kopete::Plugin inherits from KXMLGUIClient.  That client is added
  82.  * to the Kopete's mainwindow KXMLGUIFactory. So you may add actions
  83.  * on the main window (for hinstance in the meta contact popup menu).
  84.  * Please note the the client is added right after the plugin is created.
  85.  * so you have to create every actions in the constructor
  86.  *
  87.  * @author Duncan Mac-Vicar P. <duncan@kde.org>
  88.  * @author Olivier Goffart <ogoffart @ tiscalinet.be>
  89.  */
  90. class KOPETE_EXPORT Plugin : public QObject, public KXMLGUIClient
  91. {
  92.     Q_OBJECT
  93.  
  94. public:
  95.     Plugin( KInstance *instance, QObject *parent, const char *name );
  96.     virtual ~Plugin();
  97.  
  98.     /**
  99.      * Returns the KPluginInfo object associated with this plugin
  100.      */
  101.     KPluginInfo *pluginInfo() const;
  102.  
  103.     /**
  104.      * Get the name of the icon for this plugin. The icon name is taken from the
  105.      * .desktop file.
  106.      *
  107.      * May return an empty string if the .desktop file for this plugin specifies
  108.      * no icon name to use.
  109.      *
  110.      * This is a convenience method that simply calls @ref pluginInfo()->icon().
  111.      */
  112.     QString pluginIcon() const;
  113.  
  114.     /**
  115.      * Returns the display name of this plugin.
  116.      *
  117.      * This is a convenience method that simply calls @ref pluginInfo()->name().
  118.      */
  119.     QString displayName() const;
  120.  
  121.     /**
  122.      * @brief Get the plugin id
  123.      * @return the plugin's id which is gotten by calling QObject::className().
  124.      */
  125.     QString pluginId() const;
  126.  
  127.     /**
  128.      * Return the list of all keys from the address book in which the plugin
  129.      * is interested. Those keys are monitored for changes upon load and
  130.      * during runtime. When the key actually changes, the plugin's
  131.      * addressBookKeyChanged( Kopete::MetaContact *mc, const QString &key )
  132.      * is called.
  133.      * You can add fields to the list using @ref addAddressBookField()
  134.      */
  135.     QStringList addressBookFields() const;
  136.  
  137.     /**
  138.      * Return the index field as set by @ref addAddressBookField()
  139.      */
  140.     QString addressBookIndexField() const;
  141.  
  142.     /**
  143.      * Mode for an address book field as used by @ref addAddressBookField()
  144.      */
  145.     enum AddressBookFieldAddMode { AddOnly, MakeIndexField };
  146.  
  147.     /**
  148.      * Add a field to the list of address book fields. See also @ref addressBookFields()
  149.      * for a description of the fields.
  150.      *
  151.      * Set mode to MakeIndexField to make this the index field. Index fields
  152.      * are currently used by Kopete::Contact::serialize to autoset the index
  153.      * when possible.
  154.      *
  155.      * Only one field can be index field. Calling this method multiple times
  156.      * as index field will reset the value of index field!
  157.      */
  158.     void addAddressBookField( const QString &field, AddressBookFieldAddMode mode = AddOnly );
  159.  
  160.     /**
  161.      * @brief Prepare for unloading a plugin
  162.      *
  163.      * When unloading a plugin the plugin manager first calls aboutToUnload()
  164.      * to indicate the pending unload. Some plugins need time to shutdown
  165.      * asynchronously and thus can't be simply deleted in the destructor.
  166.      *
  167.      * The default implementation immediately emits the @ref readyForUnload() signal,
  168.      * which basically makes the shutdown immediate and synchronous. If you need
  169.      * more time you can reimplement this method and fire the signal whenever
  170.      * you're ready. (you have 3 seconds)
  171.      *
  172.      * @ref Kopete::Protocol reimplement it.
  173.      */
  174.     virtual void aboutToUnload();
  175.  
  176. signals:
  177.     /**
  178.      * Notify that the settings of a plugin were changed.
  179.      * These changes are passed on from the new KCDialog code in kdelibs/kutils.
  180.      */
  181.     void settingsChanged();
  182.  
  183.     /**
  184.      * Indicate when we're ready for unload.
  185.      * @see aboutToUnload()
  186.      */
  187.     void readyForUnload();
  188.  
  189. public slots:
  190.  
  191.     /**
  192.      * deserialize() and tell the plugin
  193.      * to apply the previously stored data again.
  194.      * This method is also responsible for retrieving the settings from the
  195.      * address book. Settings that were registered can be retrieved with
  196.      * @ref Kopete::MetaContact::addressBookField().
  197.      *
  198.      * The default implementation does nothing.
  199.      *
  200.      * @todo we probably should think to another way to save the contacltist.
  201.      */
  202.     virtual void deserialize( MetaContact *metaContact, const QMap<QString, QString> &data );
  203.  
  204.  
  205. protected:
  206.     virtual void virtual_hook( uint id, void *data );
  207.  
  208. private:
  209.     class Private;
  210.     Private *d;
  211. };
  212.  
  213.  
  214. } //END namespace Kopete
  215.  
  216.  
  217. #endif
  218.